【コピペで使える】Markdownコードブロックの書き方完全ガイド｜主要言語一覧＆エスケープ対策

Markdown（マークダウン）で技術ブログ、GitHubのREADME、仕様書、社内Wiki、プログラミング学習ノートを書く際に、エンジニアにとって最も利用頻度が高く重要な記法が「Markdown コードブロック（markdown code block）」と「Markdown インラインコード（inline code）」です。

「マークダウンのコードブロックでプログラムを綺麗にシンタックスハイライト（構文色分け）したい」「Python、JavaScript、TypeScript、SQL、Bash、Dockerfileなどの正しい言語指定子を一覧表で確認してコピペしたい」「コードブロックの中でバッククォート3つ（“`）をそのまま表示・エスケープさせるには？」「QiitaやZennのようにファイル名を表示したり、長いコードを折りたたむ方法は？」といった疑問や悩みを抱える方は非常に多く存在します。

Markdownのコードブロックとシンタックスハイライトを正しく使いこなせるようになると、ソースコードの視認性や可読性が劇的に向上し、誰にとっても読みやすく美しい技術文書を瞬時に作成できるようになります。

この記事では、コピペですぐに使える基本構文から、主要プログラミング言語のシンタックスハイライト指定子一覧表、インラインコードとの明確な使い分けルール、バッククォート自体のエスケープ技、diff差分ハイライト、ファイル名表示や折りたたみ表示の実践テクニックまで、網羅的かつ分かりやすく徹底解説します！

【コピペで即解決】Markdownコードブロック基本構文と主要言語一覧表

まずは、「今すぐ書き方を確認してコピーしたい」というエンジニアやブロガー向けに、コードブロックの基本構文と主要プログラミング言語のシンタックスハイライト指定名を一覧表にまとめました。

基本構文（バッククォート3つ：“`）の書き方

Markdownで複数行のプログラムコードやコマンドラインの実行ログを表示する最も標準的な方法が、コードの開始行と終了行をバッククォート3つ（```）で挟む「フェンス記法（Fenced Code Blocks）」です。

キーボードにおけるバッククォート記号（`）の入力方法は以下の通りです：

• 日本語JISキーボード（Mac）： Shift + @
• 日本語JISキーボード（Windows）： Shift + @
• US配列キーボード： `（キーボード左上、Esc の直下または Tab の上にあるキー）

```
function greet(name) {
    return "Hello, " + name + "!";
}
console.log(greet("World"));
```

function greet(name) {
    return "Hello, " + name + "!";
}
console.log(greet("World"));

バッククォート3つで囲んだ部分は、HTML変換時に <pre><code>...</code></pre> タグに変換されます。そのため、プログラムのインデント（半角スペースやタブ）や空行がそのまま等幅フォントで正確に保持されます。

主要プログラミング言語のシンタックスハイライト指定子一覧表

Markdownコードブロックの真価を発揮するのが「シンタックスハイライト（Syntax Highlighting）」です。開始バッククォート（```）の直後に、対象言語の識別子（小文字）をスペースを空けずに記述することで、構文に応じた美しい色分けが自動適用されます。

実務や技術ブログでよく使われる主要なプログラミング言語・マークアップ言語・設定ファイル・インフラ構成ファイルの指定名（識別子およびエイリアス）をジャンル別に完全網羅しました。

インラインコードとコードブロックの使い分け

Markdownには、複数行にわたるプログラムコードを掲載するコードブロックのほかに、文章の途中に埋め込んで変数やコマンドをハイライト表示する「Markdown インラインコード（inline code）」が用意されています。この2つを適切に使い分けることが、読みやすく洗練された技術ドキュメントを作るための基本です。

インラインコード（バッククォート1つ：`）の書き方と文中ハイライト

Markdown インラインコードを作成するには、装飾したい単語やフレーズをバッククォート1つ（`）で左右から囲みます。

パッケージをインストールするには `npm install axios` を実行し、
`package.json` の `dependencies` に追加されたことを確認してください。

インラインコードで囲んだ部分は、HTMLの <code>...</code> タグに変換され、背景色や文字色が変化して視覚的に引き立ちます。読者が「どこがコマンドで、どこが通常の説明文なのか」を一目で識別できるようになります。

文章内でインラインコードを使うべき代表的な要素は以下の通りです：

• 変数名・関数名・クラス名： const userData, getUserInfo(), AuthService
• ターミナルコマンド・CLIオプション： git commit -m "feat: login", docker compose up -d, --save-dev
• ファイル名・ディレクトリパス： .env.local, /etc/nginx/nginx.conf, src/components/Header.tsx
• HTMLタグ・CSSクラス名： <div>, <a href="...">, class="container"
• APIエンドポイント・HTTPステータス： GET /api/v1/users, 404 Not Found, 200 OK
• 環境変数・設定キー名： NODE_ENV=production, PORT=3000

複数行コードブロックとの明確な使い分けルール

「どちらを使うべきか」で迷った際は、以下の機能比較表をチェックしてください。

実務における判断基準はとても明快です。「複数行にわたるコードや、読者がワンクリックでコピーして実行したいスニペットはコードブロック」「文章の流れを止めずに単語として言及したい要素はインラインコード」と使い分けることで、ノイズのない美しい技術文書に仕上がります。

実務で差がつく応用テクニック＆トラブル対策

ここからは、実際の開発現場や技術ブログ執筆で差がつく、Markdownコードブロックの一歩進んだ応用テクニックとトラブルシューティングを紹介します。

コードブロック内でバッククォート（“`）を表示・エスケープする方法

Markdown自体の書き方を解説するブログや社内マニュアルを作成していると、「コードブロックの中にバッククォート3つ（“`）をそのまま記述して読者に見せたい」というケースが必ず発生します。

通常通りに ``` の中に ``` を書くと、外側のブロックが途中で勝手に終了してしまい、構文エラーとなってしまいます。このエスケープ問題を解決するルールは2通りあります。

方法1：外側を4連バッククォート（““）で囲む（最も確実・推奨）

CommonMarkおよびGFM（GitHub Flavored Markdown）の仕様では、「外側のバッククォートの数を内側よりも多くする」ことで、内側のバッククォートを安全にエスケープできます。

````markdown
以下のようにMarkdownコードブロックを記述します：

```python
def hello():
    print("Hello World")
```
````

以下のようにMarkdownコードブロックを記述します：

```python
def hello():
    print("Hello World")
```

もし内部に4連バッククォートを含めたい場合は、外側を5連バッククォート（`````）にすることで、何段階でもネストしてエスケープ可能です。

方法2：チルダ3つ（~~~）のコードブロック記法を使う

もう1つの解決策は、外側の囲み記号にチルダ3つ（~~~）を採用する記法です。囲み文字の種類自体が異なるため、内部のバッククォート3つを一切誤認することなく出力できます。

~~~markdown
```javascript
console.log("チルダ記法ならエスケープが直感的");
```
~~~

実務で頻出！diff記法によるコード差分（追加・削除）のカラー強調

Pull Request（PR）の説明文や、ブログで「コードの修正前後」を解説する際は、言語指定に diff を指定するのが極めて効果的です。

```diff
  function calculatePrice(price, taxRate) {
-     return price * taxRate; // 修正前：税額のみ返していたバグ
+     return price * (1 + taxRate); // 修正後：税込合計金額を返す
  }
```

  function calculatePrice(price, taxRate) {
-     return price * taxRate; // 修正前：税額のみ返していたバグ
+     return price * (1 + taxRate); // 修正後：税込合計金額を返す
  }

行頭に半角マイナス（-）を置くと赤色（削除行）、半角プラス（+）を置くと緑色（追加行）としてハイライトされます。変更のない前後の行は、行頭に半角スペースを2個入れておきます。

ファイル名表示やタイトル表示（GitHub/Qiita/Zenn等の対応状況）

実務の仕様書やチュートリアル記事では、「どのファイルに書くコードなのか」を明示したい場面が頻繁にあります。プラットフォームごとの記法を把握しておきましょう。

• Qiita（キータ）： 言語名の後ろにコロン（:）を付け、ファイル名を続けて記述します。

  ```python:src/main.py
  print("Qiitaスタイルのファイル名表示")
  ```

• Zenn（ゼン）： 言語名の後ろにコロン（:）または半角スペースを空けてファイル名を記述します。

  ```typescript:src/utils/math.ts
  export const add = (a: number, b: number) => a + b;
  ```

• Docusaurus / VitePress / Astro（MDX系）： title="ファイル名" 属性を付与します。

  ```javascript title="next.config.js"
  module.exports = { reactStrictMode: true };
  ```

• GitHub / 標準Markdown（共通ルール）： 標準仕様にはファイル名表示機能がないため、コードブロックの直前に太字やアイコン、引用ブロックでファイルパスを明示します。

  📁 <strong>docker-compose.yml</strong>
  ```yaml
  version: '3.8'
  services:
    app:
      build: .
  ```

なお、ConfluenceやNotion、Teamsなどの社内情報共有ツールでソースコードを共同管理する場合は、マークダウンマクロやコードブロック機能と連携することで、シンタックスハイライト付きで綺麗にナレッジを蓄積できます。社内Wikiでのコード共有やMarkdown活用法については、【チーム共有】Markdown共有ツール・社内Wikiおすすめ比較でも詳しく解説しています。

インデント（半角スペース4つ）による古いコード記法との違いと非推奨の理由

初期のMarkdown（オリジナル仕様）では、行頭に半角スペース4個（またはタブ1個）を挿入することでコードブロックにする「インデント記法」が使われていました。

現在では、GitHub Flavored Markdown（GFM）をはじめとする主要なMarkdown環境においてフェンス記法（```）が圧倒的な標準となっています。インデント記法はリスト記述時の誤作動の原因にもなりやすいため、原則としてフェンス記法のみを使用しましょう。

Markdownコードブロックに関するよくある質問（FAQ）

Markdownのコードブロックを利用する際にエンジニアからよく寄せられる質問とその解決策をQ&A形式でまとめました。

Q1. シンタックスハイライトが正しく色分けされない原因は何ですか？

Q2. 長いコードを折りたたみ表示（<details> タグ併用）にするには？

<details>
<summary>【クリックして開く】完全な設定ファイル（nginx.conf）を見る</summary>

```nginx
server {
    listen 80;
    server_name example.com;
    root /var/www/html;
}
```

</details>

Q3. 行番号を表示させる標準的な記法はありますか？

まとめ｜Markdownコードブロックをマスターして読みやすい技術文書を作ろう

今回は、Markdownコードブロック（フェンス記法）の基本構文から、主要プログラミング言語のシンタックスハイライト指定子一覧表、インラインコードとの使い分けルール、バッククォートのエスケープ技、diff差分ハイライト、ファイル名表示や折りたたみ表示まで幅広く徹底解説しました。

コードブロックを適切に使いこなすことで、あなたの作成する技術ブログ、README、仕様書の視認性と信頼性は格段に高まります。ぜひ日々の開発ドキュメント作成に活用してください！